{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "0",
   "metadata": {},
   "source": [
    "**STAC Agent - Natural Language Satellite Imagery Search**\n",
    "\n",
    "[![image](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/opengeos/geoai/blob/main/docs/examples/STAC_agents.ipynb)\n",
    "\n",
    "This notebook demonstrates how to use the STAC (SpatioTemporal Asset Catalog) Agent to search for satellite and aerial imagery using natural language queries.\n",
    "\n",
    "The STAC Agent can:\n",
    "- Understand natural language queries about geospatial data\n",
    "- Search the [Microsoft Planetary Computer STAC catalog](https://planetarycomputer.microsoft.com/catalog)\n",
    "- Convert location names to coordinates\n",
    "- Find appropriate collections and items\n",
    "- Return structured results with item IDs, URLs, and metadata\n",
    "\n",
    "Uncomment the following line to install [geoai](https://opengeoai.org) if needed."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1",
   "metadata": {},
   "source": [
    "## Installation"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2",
   "metadata": {},
   "outputs": [],
   "source": [
    "# %pip install \"geoai-py[agents]\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3",
   "metadata": {},
   "source": [
    "## Import libraries"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4",
   "metadata": {},
   "outputs": [],
   "source": [
    "import json\n",
    "from geoai import Map\n",
    "from geoai.agents import (\n",
    "    STACAgent,\n",
    "    STACTools,\n",
    "    create_ollama_model,\n",
    "    create_openai_model,\n",
    "    create_anthropic_model,\n",
    "    create_bedrock_model,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5",
   "metadata": {},
   "source": [
    "## Create a model\n",
    "\n",
    "You can create a model with the following functions:\n",
    "\n",
    "- `create_ollama_model`: Create a model using Ollama. You will need to install [Ollama]([text](https://ollama.com/download)) separately and pull the model you want to use, such as `llama3.1`.\n",
    "- `create_openai_model`: Create a model using OpenAI. You will need an OpenAI API key. Set it in the `OPENAI_API_KEY` environment variable.\n",
    "- `create_anthropic_model`: Create a model using Anthropic. You will need an Anthropic API key. Set it in the `ANTHROPIC_API_KEY` environment variable.\n",
    "- `create_bedrock_model`: Create a model using Bedrock. You will need an AWS account and the `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables set.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6",
   "metadata": {},
   "outputs": [],
   "source": [
    "model = create_ollama_model(model=\"llama3.1\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7",
   "metadata": {},
   "source": [
    "## Call STAC tools directly"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8",
   "metadata": {},
   "outputs": [],
   "source": [
    "tools = STACTools()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9",
   "metadata": {},
   "outputs": [],
   "source": [
    "tools.list_collections()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "10",
   "metadata": {},
   "outputs": [],
   "source": [
    "tools.list_collections(filter_keyword=\"landsat\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "11",
   "metadata": {},
   "outputs": [],
   "source": [
    "agent = STACAgent(model=model)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "12",
   "metadata": {},
   "outputs": [],
   "source": [
    "result = agent.ask(\"Find Sentinel-2 imagery over San Francisco in August 2025\")\n",
    "json.loads(result)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "13",
   "metadata": {},
   "source": [
    "## Show the agent UI"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "14",
   "metadata": {},
   "outputs": [],
   "source": [
    "m = Map(center=[-100, 40], zoom=3, projection=\"globe\")\n",
    "agent = STACAgent(model=model, map_instance=m)\n",
    "agent.show_ui()"
   ]
  }
 ],
 "metadata": {
  "jupytext": {
   "default_lexer": "ipython3"
  },
  "kernelspec": {
   "display_name": "geo",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.12.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}
